Skip to content

Add documentation for source symbol selection - #15

Open
theofidry wants to merge 1 commit into
mainfrom
docs/selective-ignore-annotations
Open

theofidry wants to merge 1 commit into
mainfrom
docs/selective-ignore-annotations

Conversation

@theofidry

@theofidry theofidry commented Nov 9, 2026 •

Copy link
Copy Markdown
Member

See the stack infection/infection#3683.

🤖 Generated with Codex, with an attempt at making it better.

theofidry added a commit to infection/infection that referenced this pull request Nov 15, 2026
## Description

This PR lets `infection run` target source symbols in addition to source
and test paths. Users can select code under development without changing
`infection.json5` or knowing its source file path.

Selectors support short or qualified class names and namespace prefixes,
optionally followed by a method name, an absolute source line number, or
both:

| Selector | Mutation scope |
| --- | --- |
| `Differ` | Classes named `Differ` in files whose paths contain
`Differ` |
| `Differ::diff` | `diff()` methods in classes named `Differ` |
| `Differ::32` | Eligible nodes spanning absolute source line 32 in
classes named `Differ` |
| `Differ::diff::32` | Eligible nodes spanning line 32 within those
`diff()` methods |
| `'Infection\Differ\Differ::diff'` | A qualified class and method |
| `'Differ\'` | Classes under the `Differ` namespace, including nested
namespaces |
| `'\Differ'` | Only the global class `Differ` |

Class and method names match exactly, ignoring case; a trailing
backslash selects a namespace prefix:

| Selector | Matches | Does not match |
| --- | --- | --- |
| `Differ` | `Differ`, `App\Differ`, `App\Nested\Differ` |
`ColorizedDiffer`, `App\DifferHelper` |
| `Differ::diff` | `Differ::diff()`, `App\Differ::diff()` |
`App\Differ::diffLines()`, `App\ColorizedDiffer::diff()` |
| `'App\Differ'` | `App\Differ` | `Differ`, `Other\Differ`,
`App\Differ\Helper` |
| `'Differ\'` | `Differ\Helper`, `Differ\Nested\Helper` | `Differ`,
`App\Differ\Helper`, `DifferTools\Helper` |
| `'\Differ'` | Global `Differ` | `App\Differ`, `ColorizedDiffer` |

**Symbol selectors do not support glob-style wildcard patterns such as
`*Differ` or `App\**\Differ`, or regular expressions. Support for these
patterns is outside the scope of this version but could be added
later.** The trailing backslash supports namespace-prefix matching only.

All symbol comparisons ignore case because all currently supported
symbols are case-insensitive in PHP. Line numbers are counted from the
start of the source file.

Source paths, selectors, and test paths can be combined:

```shell
infection run \
    src/Differ/Differ.php \
    Differ::diff \
    tests/phpunit/Differ/DifferTest.php
```

The source path restricts the files considered for mutation, the
selector narrows the eligible code within those files, and the test path
independently restricts the initial test suite. Multiple symbol
selectors form a union within the shared file filter. Readable files and
directories take precedence over symbol parsing; paths inside configured
source directories select source files, while other readable paths
select tests.

Anonymous classes inside a selected class or method inherit its
selection context, including nested anonymous classes. For example,
`Differ::diff` includes code inside an anonymous class declared in
`diff()`. Its methods do not become methods of `Differ`:
`Differ::nested` does not select an anonymous class's `nested()` method.
A nested named class establishes its own context, and line constraints
still apply to each node.

Line numbers refer to the source file, starting at 1. Selection uses
each AST node's full source range. Selecting a line inside a multiline
call can therefore allow a mutation that unwraps the enclosing call. It
can also allow a mutation of the method declaration, such as
`PublicVisibility`, when the selected line is inside the body. A
mutation may therefore be reported on a different line from the one
selected.

Documentation link:
infection/infection.github.io#15

## Changes

- Positional path classification is generalised to positional argument
classification, including `PositionalArgumentsFilter`, and now separates
source paths, test paths, and symbol selectors. Parsing does not consult
the autoloader. Malformed explicit selectors and out-of-range line
numbers produce diagnostics.
- `SourceFilter` carries both file and symbol constraints. File filters
narrow the set of collected source files; a matcher compares enriched
AST nodes against the selected class, namespace prefix, method, and line
constraints.
- Symbol selection runs during AST enrichment, before covering tests are
attached and untested nodes are excluded. It marks non-selected nodes as
ineligible and preserves the complete AST.
- Scope tracking preserves the enclosing named class and method through
anonymous classes and restores that context after nested declarations.
- Visitor and mutation-generation tests cover selector unions, namespace
boundaries, case-insensitive matching, multiline expressions, method
signatures and bodies, and anonymous classes. Integration and E2E cases
cover enrichment and positional disambiguation.
- `run` has argument help for selectors; other commands retain help for
source and test paths. `config:list-sources` and `initial-test:run`
accept selectors alongside paths so users can reuse arguments from
`run`, although selectors do not affect either command's result. They
reject selectors used alone when no file filter or test-framework extra
options are present.
- ADR 0015 records how paths and symbols are distinguished, the
compatibility impact, and the alternatives.

## Breaking Changes

When `Differ` is not a readable file or directory, `infection run
Differ` now requires both a matching file path and a class whose short
name is `Differ`. Previously, it applied only the file filter.

The existing `tests/e2e/Source_Symbol_Selection` fixture demonstrates
the difference:

```shell
cd tests/e2e/Source_Symbol_Selection
../../../bin/infection run Differ
```

Given the following files:

```
src/
    Differ/
        Differ.php
        Helper.php
    Other/
        ColorizedDiffer.php
        Namespaced.php
        Global.php
```

The file filter still selects the following files:

```
src/
    Differ/
        Differ.php
        Helper.php
    Other/
        ColorizedDiffer.php
```

Each class below contains a covered `Plus` mutation. The command selects
them as follows:

| File | Declared class | Before | After |
| --- | --- | --- | --- |
| `src/Differ/Differ.php` | `SourceSymbolSelection\Differ\Differ` |
Selected | Selected |
| `src/Differ/Helper.php` | `SourceSymbolSelection\Differ\Helper` |
Selected | Excluded |
| `src/Other/ColorizedDiffer.php` | `Differ\ColorizedDiffer` | Selected
| Excluded |
| `src/Other/Namespaced.php` | `SourceSymbolSelection\Other\Differ` |
Excluded | Excluded |
| `src/Other/Global.php` | Global `Differ` | Excluded | Excluded |

The file filter still collects the three matching files; the symbol
filter narrows mutation generation to the first class. Classes named
`Differ` in files whose paths do not contain `Differ` remain outside
that file filter.

The bare name `Differ` is ambiguous: it can refer to either a path or a
symbol. ADR 0015 explains why these filters are combined.

Users can express the intended scope explicitly:

- `infection run Differ/` applies a path filter without a symbol
constraint. In this fixture, it selects both classes under
`src/Differ/`.
- `infection run 'Differ\'` selects classes under that namespace across
configured source files, including classes in nested namespaces such as
`Differ\Nested\ColorizedDiffer`. In this fixture, it selects
`Differ\ColorizedDiffer` and excludes the global class `\Differ`.
- `infection run '\Differ'` selects only the global class `Differ`.

## Reviewer Notes

The [review discussion][additive-selection-discussion] highlights a
limitation of the shared file filter: `infection run Differ
Mailer::send` does not independently add `Mailer::send()` to the run.
The bare name `Differ` supplies a path filter, so `Mailer::send()` is
selected only if its file path also contains `Differ`.

An alternative would be to treat each source argument as an independent
selection and combine those selections with OR:

| Command | Current selection | With independent selections |
| --- | --- | --- |
| `infection run Differ Mailer::send` | `Differ` classes in paths
containing `Differ`, plus `Mailer::send()` only in those paths | The
same `Differ` classes, plus `Mailer::send()` across configured source
files |
| `infection run src/Differ/ Mailer::send` | Only `Mailer::send()`
within `src/Differ/` | All eligible code within `src/Differ/`, plus
`Mailer::send()` across configured source files |
| `infection run 'App\Differ' Mailer::send` | `App\Differ` and
`Mailer::send()` across configured source files | The same selection |

Independent selections would make adding targets more intuitive, but
would remove the ability to restrict a symbol to a directory in the same
command. For example, `src/Differ/ Mailer::send` currently lets users
select one method within one directory, even if other directories
contain classes with the same short name. **Supporting both behaviours
would require grouping or a separate way to express the path
constraint.**

One approach to independent selections would be to collect the symbols
in each file first. In an experiment on the Infection codebase, my
exploratory script took about 5–6 seconds to collect all symbols. That
gives an indication of the cost of that approach, although it does not
establish the cost of every possible implementation. Faster symbol
discovery, for example through another tool written in Rust, or
aggressive caching would also add complexity.

I believe these options should be considered as future improvements and
should not block this first iteration. I also expect users to supply
these paths on demand more often than hard-code them in CI, so I
consider this compatibility change less disruptive than one affecting a
typical CI configuration. Users who do persist these arguments will need
to review them when upgrading.

The selector-only guards in `config:list-sources` and `initial-test:run`
are deliberately limited. Test-framework extra options can come from
configuration as well as positional test paths, so configured options
can bypass the guards even when the user supplies only a symbol
selector. Selectors still have no effect on those commands. More
exhaustive checks would require retaining the distinction between
positional test paths and configured options; this PR leaves that
configuration change for later.

[additive-selection-discussion]:
#3683 (comment)

## Related issues

Closes #2237.

---------

Co-authored-by: Alexey Kopytko <alexey@kopytko.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant